Libris Britannia 4

home *** CD-ROM | disk | FTP | other *** search

/ Libris Britannia 4 / science library(b).zip / science library(b) / DJGPP / QDDVX102.ZIP / contrib / dvx / docs / sockets.doc < prev next >

Wrap

Text File | 1993-07-15 | 35KB | 1,466 lines

Socket Library programming reference ------------------------------------ In order for applications to communicate with each other, whether on the same machine or different machine across a network, the Berkeley Socket Interface was chosen as the means to accomplish this in the DESQview/X environment. The reasons for this are clear. The Berkeley Socket Interface is the standard by which other X Window systems and UNIX systems use to communicate. In addition, it is network independent - in fact, a network need not be present on a standalone system. DESQview/X the Berkeley Socket Interface 4.3, or BSD 4.3. This release includes 2 different types of communication - stream (TCP) and datagram (UDP). DESQview/X, through its BSD 4.3 routines, supports both of these types. DESQview/X supplies both the include files necessary to compile an application that uses BSD 4.3 as well as a socket library that performs the low level functions. The include files needed are specified in each function's synopsis. The socket library is included in the DESQview/X System Library which should be linked into your application. Since the Berkeley Socket Interface is a well-defined (and expansive) interface, this document does not attempt to teach a user how to use BSD 4.3 Sockets - there is plenty of material that does this already. Instead, each of the BSD 4.3 Socket routines that are supported in DESQview/X will now be listed in reference form. Supported BSD 4.3 Socket Routines --------------------------------- sethostent() ************ Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> void sethostent(void); Description ----------- sethostent opens and rewinds the local HOSTS file. This call is primarily useful for resetting the HOSTS file to the first entry in preparation for calls to gethostent. See Also -------- gethostent, gethostbyname, gethostbyaddr, endhostent gethostent() ************ Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> struct hostent *gethostent(void); Description ----------- gethostent reads the next entry in the local HOSTS file, opening the file if necessary. The return value is a pointer to an structure containing the broken-out fields of a line from the HOSTS file. The structure definition is as follows: struct hostent { char *h_name; char **h_aliases; int h_addrtype; int h_length; char **h_addr_list; }; h_name Official name of the host. h_aliases A NULL terminated array of alternate names for the host. h_addrtype The type of address being returned. Always AF_INET; h_length The length, in bytes, of the address. h_addr_list A pointer to a list of network addresses for the named host. Notes ----- A macro is provided as follows to convert the BSD4.3 format h_addr_list element to a BSD4.2 format: #define h_addr h_addr_list[0] Return Values ------------- gethostent returns NULL on failure or EOF. See Also -------- sethostent, gethostbyname, gethostbyaddr, endhostent endhostent() ************ Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> void endhostent(void); Description ----------- Closes the local host file. See Also -------- sethostent, gethostent, gethostbyname, gethostbyaddr gethostbyaddr() *************** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> struct hostent *gethostbyaddr(long *addr,int addrLen,int af); Description ----------- Searches the local HOSTS file sequentially until an entry is found with an h_addr_list entry corresponding to the address pointed to by the 'addr' parameter. Return Values ------------- gethostbyaddr returns NULL on failure. Notes ----- The hostent structure is defined in the description of the gethostent call. See Also -------- sethostent, gethostent, gethostbyname, endhostent gethostbyname() *************** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> struct hostent *gethostbyname(char *name); Description ----------- Searches the local HOSTS file sequentially until an entry is found with an h_name that corresponds to the 'name' parameter. Return Values ------------- gethostbyname returns NULL on failure. See Also -------- sethostent, gethostent, gethostbyaddr, endhostent gethostname() ************* Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> int gethostname(char *name,int nameLen); Description ----------- gethostname retrieves the name of the local host. The 'name' parameter is a buffer of maximum size designated by the 'nameLen' parameter. The buffer will be filled with a null-terminated string unless insufficient space is available. Return Values ------------- gethostname returns bytes filled on success, -1 on failure. setservent() ************ Synopsis -------- #include <netdb.h> void setservent(void); Description ----------- setservent opens and rewinds the local SERVICES file. This call is primarily useful for resetting the SERVICES file to the first entry in preparation for calls to getservent. See Also -------- endservent, getservent, getservbyport, getservbyname getservent() ************ Synopsis -------- #include <netdb.h> struct servent *getservent(void); Description ----------- getservent reads the next entry in the local SERVICES file, opening the file if necessary. The return value is a pointer to an structure containing the broken-out fields of a line from the SERVICES file. The structure definition is as follows: struct servent { char *s_name; char **s_aliases; int s_port; char *s_proto; }; s_name The official name of the service. s_aliases A NULL terminated list of alternate names for the service. s_port The port number which the service uses. Port numbers are returned in network short byte order. s_proto The name of the protocol to use when contacting the service. Return Values ------------- getservent returns NULL on failure or EOF. See Also -------- setservent, getservbyname, getservbyport, endservent endservent() ************ Synopsis -------- #include <netdb.h> void endservent(void); Description ----------- endservent closes the local SERVICES file. See Also -------- setservent, getservent, getservbyport, getservbyname getservbyname() *************** Synopsis -------- #include <netdb.h> struct servent *getservbyname(char *name,char *proto); Description ----------- getservbyname searches the local SERVICES file sequentially until an entry with the s_name field matching the 'name' parameter is found. If a non-NULL 'proto' parameter is specified, the search will also include a match of the s_proto field with the 'proto' parameter. Notes ----- The servent structure is defined in the description of the getservent call. Return Values ------------- getservbyname returns NULL on failure. See Also -------- setservent, getservent, getservbyport, endservent getservbyport() *************** Synopsis -------- #include <netdb.h> struct servent *getservbyport(int port,char *proto); Description ----------- getservbyport searches the local SERVICES file sequentially until an entry with an s_port matching the 'port' parameter is found. If a a non-NULL 'proto' parameter is specified, the search will also include a match of the s_proto field with the 'proto' parameter. Notes ----- The servent structure is defined in the description of the getservent call. Return Values ------------- getservbyport returns NULL on failure. See Also -------- setservent, getservent, getservbyname, endservent setprotoent() ************* Synopsis -------- #include <netdb.h> void setprotoent(void); Description ----------- setprotoent opens and rewinds the local PROTOCOLS file. This call is primarily useful for resetting the PROTOCOLS file to the first entry in preparation for calls to getprotoent. See Also -------- getprotoent, getprotobyname, getprotobynumber, endprotoent getprotoent() ************* Synopsis -------- #include <netdb.h> struct protoent *getprotoent(void); Description ----------- getprotoent reads the next entry in the local PROTOCOLS file, opening the file if necessary. The return value is a pointer to an structure containing the broken-out fields of a line from the PROTOCOLS file. The structure definition is as follows: struct protoent { char *p_name; char **p_aliases; int p_proto; }; p_name The official name of the protocol. p_aliases A zero terminated list of alternate names for the protocol. p_proto The protocol number. Return Values ------------- getprotoent returns NULL on failure or EOF. See Also -------- setprotoent, getprotobyname, getprotobynumber, endprotoent endprotoent() ************* Synopsis -------- #include <netdb.h> void endprotoent(void); Description ----------- endprotoent closes the local PROTOCOLS file. See Also -------- setprotoent, getprotoent, getprotobyname, getprotobynumber getprotobyname() **************** Synopsis -------- #include <netdb.h> struct protoent *getprotobyname(char *name); Description ----------- getprotobyname searches the local PROTOCOLS file sequentially until an entry is found with a p_name that matches the 'name' parameter. Notes ----- The protoent structure is defined in the description of the getprotoent call. Return Values ------------- getprotobyname returns NULL on failure. See Also -------- setprotoent, getprotoent, getprotobynumber, endprotoent getprotobynumber() ****************** Synopsis -------- #include <netdb.h> struct protoent *getprotobynumber(int proto); Description ----------- getprotobynumber searches the local PROTOCOLS file sequentially until an entry is found with a p_proto that matches the 'proto' parameter. Notes ----- The protoent structure is defined in the description of the getprotoent call. Return Values ------------- getprotobynumber returns NULL on failure. See Also -------- setprotoent, getprotoent, getprotobyname, endprotoent socket Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int socket(int af,int type,int protocol); Description ----------- socket opens an endpoint for network communication. The af parameter specifies the address family desired for the socket. The following address families are supported: AF_INET Internet addressing family AF_UNIX Local (file-type) addressing family The 'type' parameter specifies the method of I/O that will be available to the socket. SOCK_STREAM and SOCK_DGRAM are supported. SOCK_STREAM type sockets provide connection oriented, stream communications. Similar to pipes, full duplex, reliable and sequenced delivery is guarenteed. In order for I/O to occur, the socket must be in a connected state. Data transfer is accomplished by way of the recv and send calls, and both blocking and non-blocking modes are supported. SOCK_DGRAM type sockets provide connectionless, datagram (fixed length) communications. There is no guarentee of reliablity or sequencing. SOCK_DGRAM sockets need not be in a connected state in order to transmit or receive data. Data transfer is accomplished by way of the recvfrom and sendto calls, and both blocking and non-blocking modes are supported. The 'protocol' parameter is ignored at this time. Return Values ------------- socket returns a non-negative descriptor on success, -1 on failure (errno as described below). Errors ------ EAFNOSUPPORT The address family specified is not supported. EPROTOTYPE The protocol specified is not supported. ESOCKTNOSUPPORT The type specified is not SOCK_STREAM or SOCK_DGRAM ENOBUFS The network has exhausted it's resources. See Also -------- accept, bind, connect, getsockname, ioctl, listen, recv, select, send, shutdown, so_close so_close() ********** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int so_close(int s); Description ----------- Closes and frees the socket descriptor referenced by 's'. If the socket is of type SOCK_STREAM and in a connected state, the connection is closed, and the remote peer is notified. If the socket is of type SOCK_STREAM and in a listening state, any connections available for acceptance will be lost. Return Values ------------- so_close returns 0 on success, -1 on failure (errno as described below). Errors ------ ENOTSOCK The specified descriptor was invalid. shutdown Synopsis -------- #include <sys/types.h> #include <sys\socket.h> int shutdown(int s,int how); Description ----------- Causes all or part of a full-duplex connection on the socket associated with s to be shut down. If how is SD_RECV, then further receives will be disallowed. If how is SD_SEND then further sends will be disallowed. If how is SD_SENDRECV then both further sends and receives will be disallowed. Return Values ------------- shutdown returns 0 on success, -1 on failure (errno as described below). Errors ------ ENOTSOCK Invalid descriptor. ENOTCONN Socket is not connected and is not a datagram socket. bind() ****** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int bind(int s,struct sockaddr_in *addr,int addrLen); Description ----------- Assigns a name to the unnamed socket referenced by 's'. The name bound to the socket is specified by the 'addr' parameter. Return Values ------------- bind returns 0 on success, -1 on failure (errno as described below). Errors ------ ENOTSOCK Invalid descriptor. EAFNOSUPPORT Invalid address family. EINVAL Socket is already bound. EADDRINUSE A socket is already bound to the address on the local host. getsockname() ************* Synopsis -------- #include <sys/types.h> #include <sys\socket.h> int getsockname(int s,struct sockaddr_in *name,int *nameLen); Description ----------- getsockname returns the name associated with socket s, assigned by a previous call to bind. The value pointed to by namelen should be initialized to the size of the buffer pointed to by 'name'. The name of the socket will be placed into the buffer pointed to by the 'name' parameter and the value pointed to by the 'namelen' parameter will be updated to the actual size of the name returned. Return Values ------------- getsockname returns 0 on success, -1 on failure (errno as described below). Errors ------ ENOTSOCK Invalid descriptor. EINVAL Socket is not bound. ioctl() ******* Synopsis -------- #include <sys/types.h> #include <sys\socket.h> int ioctl(int s,int req,char *argp); Description ----------- Modifies the I/O strategy on the socket specified by 's' to the strategy indicated by 'req' and value specified by 'argp'. For example, modification of a socket to a non-blocking I/O strategy would entail a call as follows: nonBlocking = 1l; ioctl(s, FIONBIO, (char *)&nonBlocking); Return Values ------------- ioctl returns 0 on most requests, but may return non-zero values on success for some operations. On failure, ioctl returns -1 and errno is set as described below. Errors ------ ENOTSOCK Invalid descriptor. EINVAL Invalid option specified. select() ******** Synopsis -------- #include <sys/types.h> #include <sys/time.h> int select(int width,long *read,long *write,long *except, struct timeval *timeout); Description ----------- The select call examines the bitmasks pointed to by 'read', 'write' and except and determines the readability and writeability of the sockets specified by the bits in the masks. Each bit position in the input mask designates the integer value of the socket desired for evaluation. The 'width' parameter indicates the range of selectors to be examined. The 'timeout' parameter is a pointer to a structure indicating the time to wait (block) for the selection to complete. A NULL timeout pointer indicates that the operation should block indefinitely until the select completes. A poll operation can be undertaken by passing a pointer to a timeval structure intialized to zero. Although the primary uses of select include determining whether a descriptor is readable or writeable, it can also indicate several conditions. A select can be undertaken on a SOCK_STREAM socket in a listening state to determine whether a connection is available for acceptance. This test is performed by setting the bit corresponding to the socket in the read mask, and determining whether it remains set following the call. An accept call can then be issued to retrieve the pending connection. Additionally, select can indicate a dropped connection on a SOCK_STREAM socket in a connected state. This check is performed in a manner similar to that for a listening socket (described above). An immediate recv operation can then be performed to either retrieve pending data or determine the cause of the failure. Return Values ------------- On success, select returns a non-negative indicator of the number of descriptors successfully examined. A 0 is returned if a timeout occured. On failure, select returns -1 and errno is set as described below. Errors ------ EBADF One of the descriptors specified in the bitmasks is invalid. setsockopt() ************ Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int setsockopt(int s,int level,int name,char *val,int len); Description ----------- This call provided for compatibility only. accept() ******** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int accept(int s,struct sockaddr_in *addr,int *addrLen); Description ----------- accept examines the listening socket designated by 's' for pending connections. The socket must be of type SOCK_STREAM created by a socket call, bound to an address with bind and is listening for connections after a listen call. If a connection is available, accept creates a new socket with the properties of s and returns it to the caller as the connected socket. The socket designated by 's' is still available to accept further connections. If no connections are available, and the socket is marked as non-blocking, an error is returned as described below. If the socket is marked as blocking, the call blocks until a connection is available. When a valid connection descriptor is returned, the 'addr' parameter is filled with the address of the connection partner, up to a length specified by the value pointed to by 'addrLen'. The value pointed to by 'addrLen' is then updated to reflect the actual size of the address. Return Values ------------- Like socket, accept returns a non-negative descriptor on success. On failure, it returns -1 and sets errno as described below. Errors ------ ENOTSOCK Invalid descriptor. EWOULDBLOCK No connections pending. See Also -------- accept, socket connect Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int connect(int s,struct sockaddr_in *name,int nameLen); Description ----------- For SOCK_STREAM type sockets, connect attempts to establish a connection between the socket specified by 's' and opened with a socket call and a destination socket opened with socket, bound to the destination address specified by 'name' and listening for connection requests. A SOCK_STREAM socket can only be connected once. For SOCK_DGRAM type sockets, connect specifies the destination to be used for send requests and the only peer from which datagrams can be received. Provided for convenience, this allows datagram sockets to use the recv and send calls in addition to recvfrom and sendto. SOCK_DGRAM sockets can connect multiple times and can dissolve the current connection by making a call to connect with a NULL destination name. Return Values ------------- connect returns 0 on success, -1 on failure (errno set as described below). Errors ------ ENOTSOCK Invalid descriptor. EAFNOSUPPORT Invalid address family. EISCONN Socket is already connected. EWOULDBLOCK Processing connect request. ECONNREFUSED Connection refused. EINPROGRESS Processing connect request. ETIMEDOUT Connection establishment timed out without establishing a connection. See Also -------- socket, accept, listen, select listen() ******** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int listen(int s,int backlog); Description ----------- listen prepares the SOCK_STREAM socket specified by 's', created by a socket call and bound to an address with bind, to accept connections made by other SOCK_STREAM sockets calls to connect. The connection status of the socket may be queried by calls to select, and new connections are retrieved by calls to accept. The 'backlog' parameter indicates the number of simultaneous pending connections that can be queued between accept calls. Return Values ------------- listen returns 0 on success, -1 on failure (errno set as described below). Errors ------ ENOTSOCK Invalid descriptor. ECONNREFUSED Socket not bound or non-stream. ENOBUFFS Insufficient resources. See Also -------- socket, accept, select, connect recv() ****** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int recv(int s,char *buffer,int buffLen,int flags); Description ----------- recv is used to receive data for a connected socket from it's connection peer. The 'buffer' parameter is filled up to a maximum of 'buffLen' bytes. If the socket is marked as blocking, the recv call waits until data is available on the connection. If the socket is marked as non-blocking the call returns immediately with an error code if no data is available. This call can be made after a call to select to determine the readability fo the socket. Notes ----- The 'flags' parameter is ignored. Return Values ------------- On success, recv returns a non-negative integer indicating the length of the data returned in the 'buffer' parameter. On connection termination, recv returns 0. On errors, recv returns - 1 and errno as described below. Errors ------ ENOTCONN Connection terminated. ENOTSOCK Invalid descriptor or connection failure. EWOULDBLOCK No data available. ESHUTDOWN Socket shutdown. See Also -------- send, sendto, recvfrom send() ****** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int send(int s,char *buffer,int buffLen,int flags); Description ----------- send is used to transmit data for a connected socket to it's connection peer. A maximum number of bytes will be sent corresponding to the 'buffLen' parameter. If the socket is marked as blocking, the send call will wait until all data has been sent on the connection. If the socket is marked as non- blocking, the call returns immediately with an error code if no data was sent. This call can be made after a call to select to determine the writeability of the socket. Notes ----- The 'flags' parameter is ignored. Return Values ------------- On success, send returns a non-negative integer indicating the number of bytes transmitted. On failure, -1 is returned with errno as described below. Errors ------ ENOTSOCK Invalid descriptor EWOULDBLOCK No send buffer space available. ENOTCONN Connection terminated. ESHUTDOWN Socket shutdown. See Also -------- sendto, recv, recvfrom getpeername() ************* Synopsis -------- #include <sys/types.h> #include <sys\socket.h> int getpeername(int s,struct sockaddr_in *name,int *nameLen); Description ----------- Retrieves the name of the remote peer connected to the socket specified by 's'. The 'nameLen' parameter is initialized to the maximum space available in the 'name' parameter, and is updated to reflect the actual length of the name placed into the 'name' parameter. Return Values ------------- getpeername returns 0 on success, -1 on failure (errno as described below). Errors ------ ENOTSOCK Invalid descriptor. ENOTCONN Socket is not connected. recvfrom() ********** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int recvfrom(int s, char *buffer, int len, int flags, struct sockaddr_in *from, int *flen); Description ----------- recvfrom is used to receive data for the connected, SOCK_STREAM type socket or for the SOCK_DGRAM socket specified by 's'. This call is identical to the recv call with the addition that the 'from' parameter is filled with the name of the socket sending the data. The 'flen' parameter is initialized to the maximum size of the buffer pointed to by from and updated to the actual length of the name placed into the from buffer. Notes ----- The 'flags' parameter is ignored. Return Values ------------- On success, recv returns a non-negative integer indicating the length of the data returned in the 'buffer' parameter. On connection termination, recv returns 0. On errors, recv returns - 1 and errno as described below. Errors ------ ENOTCONN Connection terminated. ENOTSOCK Invalid descriptor or connection failure. EWOULDBLOCK No data available. ESHUTDOWN Socket shutdown. See Also -------- send, sendto, recv sendto() ******** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> int sendto(int s, char *buffer, int len, int flags, struct sickaddr_in *to, int tolen); Description ----------- sendto is used to transmit data for the connected, SOCK_STREAM type socket or for the SOCK_DGRAM socket specified by 's'. This call is identical to the send call with the addition that the 'to' parameter indicates the name of the destination socket for SOCK_DGRAM sockets and is ignored for SOCK_STREAM sockets. The 'tolen' parameter is set size of the buffer to be sent. Notes ----- The 'flags' parameter is ignored. Return Values ------------- On success, send returns a non-negative integer indicating the number of bytes transmitted. On failure, -1 is returned with errno as described below. Errors ------ ENOTSOCK Invalid descriptor EWOULDBLOCK No send buffer space available. ENOTCONN Connection terminated. ESHUTDOWN Socket shutdown. See Also -------- send, recv, recvfrom htonl() ******* Synopsis -------- #include <sys/types.h> #include <netinet/in.h> long htonl(long ibmdd); /* host to network long */ int htons(int ibmdw); /* host to network short */ long ntohl(long netdd); /* network to host long */ int ntohs(int netdw); /* network to host short */ Description ----------- These routines convert 16 and 32 bit quantities between 80x86 byte ordering and network byte ordering, and vice-versa. They are most often used in combination with the SERVICES routines and Internet address routines. inet_addr() *********** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> long inet_addr(char *addrDesc); Description ----------- inet_addr returns the network long integer representation of the Internet '.' notation ASCIIZ string specified by 'addrDesc'. Return Values ------------- inet_addr -1 on invalid input string. inet_lnaof() ************ Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> long inet_lnaof(long addr); Description ----------- Returns the network byte order long integer value representing the local address portion of the Internet address specified by 'addr'. inet_makeaddr() *************** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> long inet_makeaddr(long net, long lna); Description ----------- Combines the network and local address portions specified in network byte order into a single Internet address. inet_netof() ************ Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> long inet_netof(long addr); Description ----------- Returns the network byte order long integer value representing the network portion of the Internet address specified by 'addr'. inet_network() ************** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> long inet_network(char *cp); Description ----------- Converts the Internet '.' notation address specified by 'cp' to an Internet address and returns the network portion of the address. inet_ntoa() *********** Synopsis -------- #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> char *inet_ntoa(long a); Description ----------- Converts the Internet address specified by 'a' to an Internet '.' notation ASCIIZ string representing the address. Notes ----- String is STATIC and will be overwritten with each call. setpwent() ********** Synopsis -------- #include <pwd.h> void setpwent(void); Description ----------- setpwent opens and rewinds the local password file. This call is primarily useful for resetting the password file to the first entry in preparation for calls to getpwent. getpwent() ********** Synopsis -------- #include <pwd.h> struct passwd *getpwent(void); Description ----------- getpwent reads the next entry in the local password file, opening the file if necessary. The return value is a pointer to a structure containing the broken-out fields of an entry from the password information file with the structure definition is as follows: struct passwd { char *pw_name; char *pw_passwd; int pw_uid; int pw_gid; int pw_quota; char *pw_comment; char *pw_gecos; char *pw_dir; char *pw_shell; }; pw_name Official username. pw_passwd Encrypted password for the user. pw_uid Userid for the user. pw_gid Unused at this time. pw_quota Unused at this time. pw_comment Unused at this time. pw_gecos Unused at this time. pw_dir Home directory for the user. pw_shell Unused at this time. Return Values ------------- getpwent returns: NULL on failure of EOF. See Also -------- getpwuid, getpwnam, setpwent, getlogin, getuid getpwuid() ********** Synopsis -------- #include <pwd.h> struct passwd *getpwuid(uid_t uid); Description ----------- getpwuid searches the password file sequentially for a pw_uid matching that specified by the uid parameter. When a match is found, the corresponding passwd entry is returned. Notes ----- The passwd structure is defined in the description for getpwent. Return Values ------------- getpwuid returns: NULL on failure. getpwnam() ********** Synopsis -------- #include <pwd.h> struct passwd *getpwnam(char *name); Description ----------- getpwuid searches the password file sequentially for a pw_name matching that specified by the name parameter. When a match is found, the corresponding passwd entry is returned. Notes ----- The passwd structure is defined in the description for getpwent. Return Values ------------- getpwnam returns: Null on failure. getlogin() ********** Synopsis -------- #include <pwd.h> char *getlogin(void); Description ----------- getlogin returns the username of the current system user. Notes ----- Value returned is STATIC and is updated by subsequent calls. getuid() ******** Synopsis -------- #include <pwd.h> int getuid(void); Description ----------- getuid returns the user id of the current system user. DESQview/X Extension Routines ----------------------------- In order for an application to use the BSD 4.3 Socket Library, several extension routines are needed. These perform the functions of initializing and terminating the use of the DESQview/X Berkeley Socket Interface. In addition routines are provided to facilitate communication with the Network Manager as a daemon process - see the Network Daemons Programming Reference for additional details and extension routines. so_init() ********* Synopsis -------- #include <sys\socket.h> int so_init(void); Description ----------- so_init is an extension call that initializes the DESQview/X Socket Interface and returns the availabilty of socket resources. Notes ----- DESQview/X extension call. Return Values ------------- so_init returns 1 on success, 0 on failure. so_exit() ********* Synopsis -------- #include <sys\socket.h> void so_exit(void); Description ----------- Uninitializes the socket interface for the DESQview/X process. Notes ----- DESQview/X extension call. so_setupdaemon() **************** Synopsis -------- #include <sys\socket.h> void so_setupdaemon(char *name); Description ----------- The so_setupdaemon call allows a DESQview/X application to assume the identity of a network daemon. The 'name' parameter refers to a valid entry in the local SERVICES file. Following the call, the application can then issue so_daemon calls to check for connections/datagrams - see the section Network Daemons Programming Reference for details. Notes ----- DESQview/X extension call. getpwvar() ********** Synopsis -------- #include <pwd.h> char *getpwvar(char *key, char *var); Description ----------- getpwvar returns the ASCIIZ string describing the value indicated by parameters var and key. The key parameter indicates the key into the password information file and usually indicates a username. The var parameter is the variable that has been defined in the password information file to hold the value.